// This isn't a real header. It just gives me a place to hang
// doxygen's \mainpage comment.
namespace std {
/// \mainpage Proposing array_ref<T> and string_ref
/// \xmlonly <document-number>N????=12-0???</document-number> \endxmlonly
/// \author Jeffrey Yasskin <jyasskin@google.com>
/// \author Source at http://code.google.com/p/cxx1y-array-string-ref/
///
/// \section overview Overview
///
/// References to arrays and strings are very common in C++ programs,
/// but often the callee doesn't care about the exact type of the
/// object that owns the data.  3 things generally happen in this case:
///   -# The callee picks a particular type—a \c vector, say—and
///      insists that callers copy the data if it was originally in
///      another format.
///   -# The callee takes two parameters—a pointer and a length—and
///      reduces the readability and safety of calls and loses any
///      helper functions the original type provided.
///   -# The callee is rewritten as a template and its implementation
///      is moved to a header file.  This can increase flexibility if
///      the author takes the time to code to a weaker iterator
///      concept, but it can also increase compile time and code size,
///      and can even introduce bugs if the author misses an
///      assumption that the argument's contents are contiguous.
///
/// Google and LLVM have independently implemented two types to
/// encapsulate this kind of argument.  \link std::array_ref
/// \c array_ref<T> \endlink is implicitly constructible from several
/// standard array-like types and stores a contiguous range of
/// addresses. It provides the subset of operations from \c std::array<>
/// and \c std::vector<> that work on immutable sequences.  Because \c
/// array_ref stores pointers rather than a reference to the original
/// array, it also supports a few operations to modify the current
/// view.
///
/// \link std::basic_string_ref \c string_ref \endlink is implicitly
/// constructible from <code>const char*</code> and \c std::string.
/// It provides most of the member operations from \c std::string to
/// ease conversion.  This paper follows <a
/// href="http://src.chromium.org/viewvc/chrome/trunk/src/base/string_piece.h?view=markup">Chromium</a>
/// in extending \c string_ref to <code>basic_string_ref<charT,
/// traits></code> (Chromium omits \c traits). We provide typedefs to
/// parallel the 4 \c basic_string typedefs.
///
/// Both Google's and LLVM's \c string_ref types extend the interface
/// from \c std::string to provide some helpful utility functions:
///   - \link std::basic_string_ref::starts_with starts_with \endlink
///   - \link std::basic_string_ref::ends_with ends_with \endlink
///   - \link std::basic_string_ref::remove_prefix remove_prefix \endlink
///   - \link std::basic_string_ref::remove_suffix remove_suffix \endlink
///   - split
///   - trim
///   - consume_prefix
///   - count
///
/// Versions of \c std::string operations that take \c string_ref
/// instead also give the standard a way to provide in-place
/// operations on non-null-terminated byte/character sequences:
///   - hash, as requested by c++std-lib-31935
///   - numeric conversions
///
/// Note that some of the code samples in this paper don't use full
/// C++11 conventions because they're extracted from code that
/// actually compiles, and current compilers don't yet support the
/// whole C++11 language.
///
/// \section inventions Inventions in this paper
///
/// Google's \c StringPiece provides \c as_string and \c ToString
/// methods to convert to \c std::string.  LLVM's \c StringRef
/// provides both a \c str() explicit conversion and an implicit
/// <code>operator std::string()</code>, and similarly for \c ArrayRef
/// to \c std::vector.  Since this paper builds on top of C++11, we
/// provide <em><code>explicit</code></em> conversion operators in
/// addition to two named conversions \c vec() and \c str().
///
/// Google's and LLVM's \c string_ref types provide a subset of \c
/// std::string's searching operations, but they do provide
/// '<code>pos</code>' arguments to specify where to start the search.
/// Because \c string_ref::substr is much cheaper than \c
/// string::substr, this paper removes the \c pos argument entirely.
///
/// None of the existing classes have \c constexpr methods.
///
/// \section bikeshed Bikeshed!
///
/// What do we call these?
///
/// std::array_ref:
///   - array_slice
///   - sub_array
///   - pointer_range
///
/// std::string_ref:
///   - sub_string
///   - string_piece
///   - string_view
///
/// \sa std::array_ref std::basic_string_ref
///
/// \section misc Miscellaneous other changes
///
/// Certain other pieces of the library should change to make life
/// easier for \c array_ref<> and \c string_ref.
///
///  - Several of the \c char_traits methods could be \c constexpr.
///  - It would be helpful to be able to provide separate definitions
///    for the \c constexpr and non-<code>constexpr</code> versions of
///    a function.  Specifically, sometimes the fastest-executing
///    implementation isn't in a form that \c constexpr accepts, but
///    there's still a possible \c constexpr implementation.
///
/// \section future Future work
///
/// <ul>
/// <li>It might make sense for \c std::array_ref<T> to inherit from \c
///     std::range<T*> when/if that gets standardized. On the other hand:
///     <ol>
///     <li>\c range<T*> will have an implicit conversion operator
///         from anything with \c begin() and \c end() methods, so
///         it'll already implicitly convert from \c
///         array_ref<T>. Will the inheritance still help with code
///         like the following?
///         <pre><code>template<typename T> void foo(std::range<T>)</code></pre>
///         </li>
///     <li>\c range<T*> may obviate the need for \c array_ref<T>. One
///         difficulty with using \c range<T*> instead of \c
///         array_ref<T> is that \c range<Iterator> will probably be
///         implicitly constructible from anything with a begin/end,
///         but non-template functions may want to take \c range<T*>
///         instead. One way to deal with this would be for \c
///         range<T*> to be specialized, adding constructors from
///         arbitrary contiguous iterators, but that could introduce
///         ambiguities with functions taking \c range<TplArg>.</li>
///     </ol>
/// </li>
///
/// <li>\c std::sub_match ([re.submatch]) should probably inherit from \c
/// std::string_ref, but the fact that it takes any bidirectional
/// iterator makes that tricky.</li>
///
/// <li>Consider replacing these conversion operators with new constructor
/// overloads on the target types.</li>
///
/// <li>Consider adding \c starts_with and \c ends_with methods to \c
/// basic_string.</li>
///
/// </ul>
///
/// \sa \ref todo
}
